workbench/devs/AHI/Examples/Low-level/3rd party/GetAudioID/GetAudioID.guide

   1 @database "GetAudioID.guide"
   2
   3 @author "Tomi Blinnikka"
   4 @(c) "Copyright Tomi Blinnikka 1996"
   5 @$VER: GetAudioID.guide 1.01 (01.05.96) (C) Copyright Tomi Blinnikka 1996
   6 @wordwrap
   7
   8 @node Main "GetAudioID table of contents"
   9 @next Doc_Version
  10
  11 01.05.96                    @{b}GetAudioID V1.01@{ub}
  12
  13 @{u}Table of contents@{uu}
  14
  15      @{"Document versions                   " link Doc_Version}
  16      @{"Copyright                           " link Copyright}
  17      @{"What does GetAudioID do?            " link Basics}
  18      @{"Compatibility                       " link Compatibility}
  19      @{"Starting from CLI/Shell             " link CLIStart}
  20      @{"Starting from Workbench             " link WBStart}
  21      @{"How to use the formatting string    " link Examples}
  22      @{"Error messages                      " link Errors}
  23      @{"Bugs                                " link Bugs}
  24      @{"Versions                            " link Versions}
  25      @{"Future versions                     " link Future}
  26      @{"Shareware fee                       " link Shareware}
  27      @{"Contacting the author               " link Author}
  28 @endnode
  29
  30 @node Doc_Version "Document version"
  31 @prev Main
  32 @next Copyright
  33
  34 @{u}DOCUMENT VERSIONS@{uu}
  35
  36 Updated: 30.04.96 - for version 1.00
  37 Updated: 01.05.96 - for version 1.01
  38 @endnode
  39
  40 @node Copyright "Copyright information"
  41 @prev Doc_Version
  42 @next Basics
  43
  44 @{u}COPYRIGHT INFORMATION@{uu}
  45
  46  Copyright (C) @{"Tomi Blinnikka" link "Author"} 1996, @{u}All Rights Reserved.@{uu}
  47
  48 This program is @{"SHAREWARE" link "Shareware"}. This means that you can copy it and give it
  49 to all your friends, upload it to a BBS or include it in a PD-library
  50 (FISH, Aminet CDROMS etc.). BUT (!!!) if you use this program
  51 frequently you must pay 5 to 10 USD. The other restrictions are: this archive
  52 can only be spread in its original form without additions, deletions, or
  53 modifications of any kind and it IS NOT TO BE SOLD FOR PROFIT. THIS INCLUDES
  54 GERMAN PD DEALERS. If you wish to use this program for commercial purposes,
  55 you need written permission from the author.
  56
  57 @{b}GETAUDIOID@{ub} IS PROVIDED "AS-IS" AND SUBJECT TO CHANGE;
  58 NO WARRANTIES ARE MADE.  ALL USE IS AT YOUR OWN RISK.  NO LIABILITY
  59 OR RESPONSIBILITY IS ASSUMED.
  60 @endnode
  61
  62 @node Basics "Basics about GetAudioID"
  63 @prev Copyright
  64 @next Compatibility
  65
  66 @{u}WHAT DOES IT DO?@{uu}
  67
  68 This program opens a requester asking for the desired audio mode and mixing
  69 frequency. It then returns the selected ID and frequency as a text string.
  70 Optional @{"formatting" link Examples} is supported.
  71 @endnode
  72
  73 @node Compatibility "What is GetAudioID compatible with?"
  74 @prev Basics
  75 @next CLIStart
  76
  77 @{u}COMPATIBILITY@{uu}
  78
  79 @{b}GetAudioID@{ub} requires Kickstart 2.04 or newer and ahi.device version
  80 1 or newer.
  81
  82 @endnode
  83
  84 @node CLIStart "Starting GetAudioID from a CLI/Shell"
  85 @prev Compatibility
  86 @next WBStart
  87
  88 @{u}STARTING FROM CLI/SHELL@{uu}
  89
  90 You can start the program from a CLI/SHELL/etc. and @{"Workbench" link "WBStart"}.
  91
  92 To run the program, enter the following into your CLI/SHELL/etc.
  93
  94         1> GetAudioID DEC=DECIMAL/S,TITLE/K,POSITIVE/K,NEGATIVE/K,
  95            LFORMAT/K,PUBSCREEN/K:
  96
  97         Where:  DECIMAL prints the AudioID in decimal notation instead of
  98                 the default hexadecimal one. Use DEC as an abbreviation.
  99
 100                 TITLE specifies the window title for the requester. Useful
 101                 for scripts. Keyword required.
 102
 103                 POSITIVE specifies the gadget text for the positive gadget
 104                 (the 'OK' button). Useful for scripts. Keyword required.
 105
 106                 NEGATIVE specifies the gadget text for the negative gadget
 107                 (the 'Cancel' button). Useful for scripts. Keyword required.
 108
 109                 LFORMAT allows you to specify an alternate @{"formatting" link Examples}
 110                 string for the result. Useful for scripts. Keyword
 111                 required. Double quotes may be required.
 112
 113                 PUBSCREEN specifies the public screen name where the
 114                 requester should open. Keyword required.
 115
 116 @endnode
 117
 118 @node WBStart "Starting from the Workbench"
 119 @prev CLIStart
 120 @next Examples
 121
 122 @{u}STARTING FROM WORKBENCH@{uu}
 123
 124 From Workbench, start the program like any other by double-clicking on its
 125 icon. If, however, you would like to specify a @{"formatting string" link Examples} or
 126 public screen, use the tool types. This is done by clicking once on the icon
 127 and selecting 'Information...' from the 'Icons' menu in the Workbench. Then
 128 change the tool types accordingly (please refer to your User Manual, if
 129 necessary). Please take care with upper- and lowercase letters! The inputs ARE
 130 case-sensitive. If a public screen name isn't given, @{b}GetAudioID@{ub} will
 131 use the default public screen.
 132
 133 Below is a list of available tool types and there usage:
 134
 135 TOOL TYPE       VALUE
 136 -----------------------------------------------------------------------
 137 DECIMAL         <None>
 138 TITLE           <Window title for the requester>
 139 POSITIVE        <Text for positive gadget (the 'OK' button)>
 140 NEGATIVE        <Text for negative gadget (the 'Cancel' button)>
 141 LFORMAT         <@{"Formatting string" link Examples} for the result>
 142 PUBSCREEN       <Name of the public screen to open on>
 143
 144 Examples:
 145
 146         DECIMAL
 147         TITLE=Choose sound mode
 148         POSITIVE=Okay
 149         NEGATIVE=Nope
 150         LFORMAT=The selected mode ID was %ld, mixing frequency of %ld.
 151         PUBSCREEN=My_Public_Screen.1
 152
 153 or simply
 154
 155         PUBSCREEN=Workbench
 156 @endnode
 157
 158 @node Examples "Formatting string examples"
 159 @prev WBStart
 160 @next Errors
 161
 162 @{u}HOW TO USE THE FORMATTING STRING@{uu}
 163
 164 To change the output of @{b}GetAudioID@{ub}, use the LFORMAT option. It
 165 works like the LFORMAT option of the system command List. You may enter any
 166 text you wish where the first occurance of "%ld" or "%lx" will be replaced
 167 with the ModeID selected and the second with the mixing frequency. Use "%%"
 168 to print a procent sign. @{b}NOTE:@{ub} You must use the "l" after the
 169 procent sign and no more than two occurances of "%ld" or "%lx" are allowed.
 170
 171 @{u}EXAMPLES:@{uu}
 172
 173 LFORMAT=The AudioID for the selected mode is 0x%08lx (hex) and the mixing
 174 frequency is %ld Hz.
 175
 176 LFORMAT="ID=$%lx MIX=$%lx"
 177 @endnode
 178
 179 @node Errors "Error messages displayed by GetAudioID"
 180 @prev Examples
 181 @next Bugs
 182
 183 @{u}ERROR MESSAGES@{uu}
 184
 185 The @{b}GetAudioID@{ub} program will display necessary error messages. If a library
 186 can't be opened, the user will be informed. I HATE PROGRAMS THAT DON'T TELL
 187 WHAT-THE-HELL IS GOING ON! That clear? If @{b}GetAudioID@{ub} doesn't give any
 188 output something has gone terribly wrong or you're running with an old
 189 Kickstart. Even in this case the return code will be set to -20 (FAIL).
 190 @endnode
 191
 192 @node Bugs "Known bugs"
 193 @prev Errors
 194 @next Versions
 195
 196 @{u}BUGS@{uu}
 197
 198 No known bugs at the moment. @{b}GetAudioID@{ub} has been tested with
 199 Enforcer & Mungwall.
 200 @endnode
 201
 202 @node Versions "List of versions and changes"
 203 @prev Bugs
 204 @next Future
 205
 206 @{u}VERSIONS@{uu}
 207
 208 Version Size    Date     Description
 209 ------------------------------------------------------------------------
 210 1.01    2276    01.05.96 Doesn't have a default AudioID anymore and thus
 211                          complies with the AHI standard.
 212                          Will return with code -5 (WARN) if no mode was
 213                          selected but OK was pressed.
 214
 215 1.00    2260    30.04.96 Added WB support.
 216                          Added options TITLE, POSITIVE, NEGATIVE,
 217                          LFORMAT & PUBSCREEN.
 218                          Added locale support and Finnish catalog.
 219                          Wrote documents.
 220
 221 0.00a-   N/A    29.04.96 Wrote the program basics and main routines.
 222 0.99a
 223 @endnode
 224
 225 @node Future "Future versions and ideas for them"
 226 @prev Versions
 227 @next Shareware
 228
 229 @{u}FUTURE VERSIONS@{uu}
 230
 231 Future version will have the bug fixes for the bugs I haven't found.
 232 I'm out of ideas.
 233 @endnode
 234
 235 @node Shareware "GetAudioID shareware fee"
 236 @prev Future
 237 @next Author
 238
 239 @{u}SHAREWARE FEE@{uu}
 240
 241 If you use this program on a regular basis, be kind enough to thank me with
 242 a few bucks. The suggested fee is 5 to 10 USD. This doesn't apply if you've
 243 registered @{b}AHIPlay@{ub} by @{"Tomi Blinnikka" link Author}.
 244 @endnode
 245
 246 @node Author "Contacting the author"
 247 @prev Shareware
 248
 249 @{u}CONTACTING THE AUTHOR@{uu}
 250
 251 Please send donations, @{"bug" link "Bugs"} reports, and list of features you would like to
 252 have included in @{"future versions" link "Future"} to
 253
 254 Tomi Blinnikka
 255 Syystie 10
 256 00780 Helsinki
 257 FINLAND
 258
 259 Contact me at the address above or you can also contact me on the
 260 following BBS and net address:
 261
 262 MITS +358-0-348 205
 263
 264 docbliny@walrus.megabaud.fi
 265
 266
 267 "...trademark of Xerox Corporations. Reading legal mush can turn your
 268 brain to guacamole! Epson is registered trademark of Epson America
 269 ..." -Amiga RKRM Includes & AutoDocs, fourth page.
 270
 271
 272                                                 Tomi Blinnikka
 273
 274                                                 docbliny@walrus.megabaud.fi
 275 @endnode